<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**
 * This file is part of the PEAR Services_RickProof package.
 *
 * PHP version 5
 *
 * LICENSE: This source file is subject to the MIT license that is available
 * through the world-wide-web at the following URI:
 * http://opensource.org/licenses/mit-license.php
 *
 * @category  Services 
 * @package   Services_RickProof
 * @author    David JEAN LOUIS <izimobil@gmail.com>
 * @copyright 2008 David JEAN LOUIS
 * @license   http://opensource.org/licenses/mit-license.php MIT License 
 * @version   CVS: $Id$
 * @link      http://pear.php.net/package/Services_RickProof
 * @since     File available since release 0.1.0
 * @filesource
 */

require_once 'Services/RickProof/Exception.php';
require_once 'Services/RickProof/Result.php';

/**
 * Services_RickProof is an interface for communicating with rickproof.com, 
 * you can check any suspect URL with this package and you will never get rick 
 * rolled again !
 *
 * This package is "never gonna give you up !" (tm).
 *
 * Here's an example on how to use Services_RickProof (note that this example 
 * is also a DocTest (@see: http://pear.php.net/package/Testing_DocTest)):
 *
 * <code>
 * // valid tests
 * echo Services_RickProof::check('http://google.com') . "\n";
 * echo Services_RickProof::check('http://is.gd/2kz')  . "\n";
 * try {
 *     // wrong url template (htp vs http)
 *     Services_RickProof::$urlTemplate = 'htp://rickproof.com/?q=%s&s=1';
 *     echo Services_RickProof::check('foo')  . "\n";
 * } catch (Exception $exc) {
 *     echo $exc->getMessage() . "\n";
 * }
 * try {
 *     // wrong url template (s=1 parameter missing)
 *     Services_RickProof::$urlTemplate = 'http://rickproof.com/?q=%s';
 *     echo Services_RickProof::check('foo')  . "\n";
 * } catch (Exception $exc) {
 *     echo $exc->getMessage() . "\n";
 * }
 * // expects:
 * // Minimal Risk (level: 0)
 * // Extreme Risk (level: 10)
 * // Unable to retrieve url "htp://rickproof.com/?q=foo&s=1"
 * // Unable to parse response (url called: "http://rickproof.com/?q=foo")
 * </code>
 *
 * @category  Services
 * @package   Services_RickProof
 * @author    David JEAN LOUIS <izimobil@gmail.com>
 * @copyright 2008 David JEAN LOUIS
 * @license   http://opensource.org/licenses/mit-license.php MIT License 
 * @version   Release: @package_version@
 * @link      http://pear.php.net/package/Services_RickProof
 * @since     Class available since release 0.1.0
 */
class Services_RickProof
{
    // properties {{{

    /**
     * The service URL template.
     *
     * @var    string $url the service url template
     * @access public
     */
    public static $urlTemplate = 'http://rickproof.com/?q=%s&s=1';

    // }}}
    // check() {{{

    /**
     * Check if the given url is "rickproof" and return a
     * Services_RickProof_Result instance or throw a
     * Services_RickProof_Exception if something wrong occurs.
     *
     * @param string $url the URL to check
     *
     * @access public
     * @return object Services_RickProof_Result
     * @throws Services_RickProof_Exception if an error occurs
     */
    public static function check($url)
    {
        $endpoint = sprintf(self::$urlTemplate, urlencode($url));
        $html     = @file_get_contents($endpoint);
        if (false === $html) {
            throw new Services_RickProof_Exception(
                "Unable to retrieve url \"$endpoint\""
            );
        }
        $rx = '/<span class="no(\d+)".*?<p>(.+Risk)<\/p>/ms';
        if (preg_match($rx, $html, $tokens)) {
            return new Services_RickProof_Result($tokens[1], $tokens[2]);
        }
        throw new Services_RickProof_Exception(
            "Unable to parse response (url called: \"$endpoint\")"
        );
    }

    // }}}
}
